/*******************************************************************************
 * Copyright 2000, 2006 Visual Systems Corporation.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the GNU Public License version 2
 * which accompanies this distribution in a file named "COPYING".
 * 
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *      
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *      
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 *******************************************************************************/
// Ener-J
// Copyright 2001, 2002 Visual Systems Corporation
// $Header: /cvsroot/ener-j/ener-j/src/org/enerj/core/Persistable.java,v 1.1 2005/08/16 04:24:45 dsyrstad Exp $

package org.enerj.core;

import java.io.IOException;


/**
 * Persistable interface for classes that may be persisted.
 * This interface is intended ONLY for internal use by Ener-J.
 *
 * @version $Id: Persistable.java,v 1.1 2005/08/16 04:24:45 dsyrstad Exp $
 * @author <a href="mailto:dsyrstad@ener-j.org">Dan Syrstad</a>
 */
public interface Persistable 
{

    // Note: the methods below are intended to be invoked only by the
    // Ener-J internal implementation. Their implementation is generated by 
    // the enhancer.



    /**
     * Get the modification version number associated with this object.
     *
     * @return the Version.
     */
    public long enerj_GetVersion();


    /**
     * Set the modification version for this object.
     *
     * @param aVersion the modification version number.
     */
    public void enerj_SetVersion(long aVersion);


    /**
     * Get the object ID this object. There is only one spot in the code
     * that should call this method (EnerJDatabase - hence the word "Private" in the
     * name). If you need the OID,
     * call org.enerj.core.EnerJDatabase.getOID(), or call 
     * org.odmg.Implementation.getObjectId().
     *
     * @return the OID, or zero (the null OID) if the object is new and an OID 
     *  hasn't been assigned yet (this object is not yet part of the persistable
     *  object graph).
     */
    public long enerj_GetPrivateOID();


    /**
     * Set the object ID for this object. Only EnerJDatabase should call this method.
     *
     * @param anOID the OID.
     */
    public void enerj_SetPrivateOID(long anOID);


    /**
     * Get the Persister associated with this object.
     * This method is generated only on the least-derived Persistable super-class.
     *
     * @return the Persister, or null if the object is not currently associated with 
     *  a Persister.
     */
    public Persister enerj_GetPersister();


    /**
     * Set the Persister associated with this object.
     * This method is generated only on the least-derived Persistable super-class.
     *
     * @param aPersister the Persister, or null if the object is not currently associated with 
     *  a Persister.
     */
    public void enerj_SetPersister(Persister aPersister);


    /**
     * Gets the lock level of this object. This is merely the local status of the lock.
     * 
     * @return one of the EnerJTransaction lock levels: NO_LOCK, READ,
     *  UPGRADE, or WRITE.
     */
    public int enerj_GetLockLevel();


    /**
     * Sets the lock level of this object. This does not actually lock the object,
     * it merely maintains a local status of the lock.
     * 
     * @param aLockLevel one of the EnerJTransaction lock levels: NO_LOCK, READ,
     *  UPGRADE, or WRITE.
     */
    public void enerj_SetLockLevel(int aLockLevel);
    

    /**
     * Gets the Class Id (CID) for the Class of this Persistable. This
     * is here for non-reflective access when a Persistable is available.
     * If only the Class of the Persistable is available, then the static version
     * of this method (enerj_GetClassIdStatic) should be used.
     */
    public long enerj_GetClassId();
    

    /**
     * Sets whether this object is Modified.
     */
    public void enerj_SetModified(boolean aModifiedFlag);
    

    /**
     * Determines if this object has been Modified.
     *
     * @return true if it was Modified, else false.
     */
    public boolean enerj_IsModified();


    /**
     * Sets whether this object is Loaded.
     */
    public void enerj_SetLoaded(boolean aLoadedFlag);


    /**
     * Determines if this object has been Loaded.
     *
     * @return true if it has been Loaded, else false.
     */
    public boolean enerj_IsLoaded();


    /**
     * Sets whether this object is New.
     */
    public void enerj_SetNew(boolean aNewFlag);


    /**
     * Determines if this object is New.
     *
     * @return true if it is New, else false.
     */
    public boolean enerj_IsNew();


    /**
     * Sets whether this object allows Non-Transactional Reads.
     */
    public void enerj_SetAllowNonTransactionalRead(boolean anAllowFlag);


    /**
     * Determines if this object allows Non-Transactional Reads.
     *
     * @return true if it allows Non-Transactionals Reads, else false.
     */
    public boolean enerj_AllowsNonTransactionalRead();


    /**
     * Sets whether this object allows Non-Transactional Writes.
     */
    public void enerj_SetAllowNonTransactionalWrite(boolean anAllowFlag);


    /**
     * Determines if this object allows Non-Transactional Writes.
     *
     * @return true if it allows Non-Transactionals Writes, else false.
     */
    public boolean enerj_AllowsNonTransactionalWrite();


    /**
     * Read the object's persistent field values from the specified read context.
     * The object's in-memory state is updated.
     *
     * @param aContext an ObjectSerializer.
     *
     * @throws IOException if an error occurs.
     */
    public void enerj_ReadObject(ObjectSerializer aContext) throws IOException;


    /**
     * Write the object's persistent field values to the specified write context.
     * The object's in-memory state is not changed.
     *
     * @param aContext an ObjectSerializer.
     *
     * @throws IOException if an error occurs.
     */
    public void enerj_WriteObject(ObjectSerializer aContext) throws IOException;


    /**
     * Resolve the object's entire object graph recursively until all instances are fully loaded.
     * This allows the object's entire graph to be used without a dependence on the persister (i.e.,
     * {@link #enerj_GetPersister()} will return null.
     *
     * @param aContext an ObjectSerializer.
     * @param shouldDisassociate if true, the object tree will be disassociated from 
     *  its Persister.
     *
     * @throws IOException if an error occurs.
     */
    public void enerj_ResolveObject(ObjectSerializer aContext, boolean shouldDisassociate) throws IOException;


    /**
     * Clear the object's persistent fields. Only persistent fields which
     * refer to Objects are cleared (i.e., primitive field values are not touched).
     */
    public void enerj_Hollow();
}
